package graphs;
import java.awt.Canvas;
import java.util.HashMap;
import java.util.ListIterator;
import tester.Example;
import tester.cobertura.Instrument;

/**
 * <h1>Title : IGraph</h1>
 * <p>Description : The graph interface, specifies a weighted and plotable
 * graph. All graph representations use this Interface
 * to deal with graphs.</p>
 * 
 * @author Adam Blackwell & Ryan Cassidy
 * @version 1.2
 * @since February 22nd 2009
 */
@Instrument @Example public interface IGraph {
 
  //=========================
  // Construction methods:
  //=========================
  
  /**
   * <p>AddVertex : Adds a vertex.</p>
   * @param vertex to add to the graph
   */
  public void addVertex(Vertex vertex);
  
  /**
   * <p>RemoveVertex : Removes a vertex.</p>
   * @param vertex to remove from the graph
   */
  public void removeVertex(Vertex vertex);
  
  /**
   * <p>AddEdge : Adds an Edge, by adding the two links in both directions.
   * If you want a directional graph create an addLink method in the representation.</p>
   * @param startVertex
   * @param destinationVertex
   * @param weight
   */
  public void addEdge(Vertex startVertex, Vertex destinationVertex, int weight);
  
  /**
   * <p>RemoveEdge : Removes the edge between the two given vertices, if it exists.</p>
   * @param startVertex
   * @param destinationVertex
   */
  public void removeEdge(Vertex startVertex, Vertex destinationVertex);
  
  // =========================
  // Exist methods:
  // =========================
  
  /**
   * <p>EdgeExist : Checks if the Edge exists that lies between the two given vertices.</p>
   * @param startVertex
   * @param destinationVertex
   * @return whether it is or not
   */
  public boolean edgeExist(Vertex startVertex, Vertex destinationVertex);
  
  /**
   * <p>VertexExist : Checks if the given Vertex is in the graph representation.</p>
   * @param vertex
   * @return whether it is or not
   */
  public boolean vertexExist(Vertex vertex);

  // =========================
  // Getters:
  // =========================
  
  /**
   * <p>GetEdgeWeight : Pulls the integer value of the Edge's weight from 
   * the start vertes's neighbors list.</p>
   * @param startVertex
   * @param destinationVertex
   * @return the weight between the two vertices
   */
  public int getEdgeWeight(Vertex startVertex, Vertex destinationVertex);
  
  /**
   * <p>GetAdjacentVertices : Creates the given Vertex's neighbors listIterator.</p>
   * @param vertex
   * @return the iterable representation of the vertices neighbors list
   */
  public ListIterator<Vertex> getAdjacentVertices(Vertex vertex);
  
  /**
   * <p>GetAdjacentVertexNames : Creates the gievn vertexes listiterator of names.>/p>
   * @param vertex
   * @return
   */
  public ListIterator<String> getAdjacentVertexNames(Vertex vertex);
  
  /**
   * <p>GetVerticesNumber : Calculates how many vertices there are.</p>
   * @return number of vertices
   */
  public int getVerticesNumber();
  
  /**
   * <p>GetVerticesMap : Getter method...</p>
   * @return the hashmap of vertices
   */
  public HashMap<String, Vertex> getVerticesMap();
  
  /**
   * <p>GetDirected : Getter method...</p>
   * 
   * @return whether or not the graph is directed
   */
  public boolean getDirected();
}
